home *** CD-ROM | disk | FTP | other *** search
/ Java Programmer's Toolkit / Java Programmer's Toolkit.iso / src / java / awt / graphi~1.jav < prev    next >
Encoding:
Text File  |  1996-01-12  |  17.1 KB  |  512 lines
  1. /*
  2.  * @(#)Graphics.java    1.29 95/12/14 Sami Shaio
  3.  *
  4.  * Copyright (c) 1995 Sun Microsystems, Inc. All Rights Reserved.
  5.  *
  6.  * Permission to use, copy, modify, and distribute this software
  7.  * and its documentation for NON-COMMERCIAL purposes and without
  8.  * fee is hereby granted provided that this copyright notice
  9.  * appears in all copies. Please refer to the file "copyright.html"
  10.  * for further important copyright and licensing information.
  11.  *
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  13.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  14.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  15.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  16.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  17.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  18.  */
  19. package java.awt;
  20.  
  21. import java.io.*;
  22. import java.lang.*;
  23. import java.util.*;
  24. import java.awt.image.ImageObserver;
  25.  
  26. /**
  27.  * Graphics is the abstract base class for all graphic 
  28.  * contexts for various devices. 
  29.  * 
  30.  * @version     1.29, 12/14/95
  31.  * @author     Sami Shaio
  32.  * @author     Arthur van Hoff
  33.  */
  34. public abstract class Graphics {
  35.  
  36.     /**
  37.      * Constructs a new Graphics Object. Graphic contexts cannot be 
  38.      * created directly. They must be obtained from another graphics
  39.      * context or created by a Component.
  40.      * @see Component#getGraphics
  41.      * @see #create
  42.      */
  43.     protected Graphics() {
  44.     }
  45.  
  46.     /**
  47.      * Creates a new Graphics Object that is a copy of the original Graphics Object.
  48.      */
  49.     public abstract Graphics create();
  50.  
  51.     /**
  52.      * Creates a new Graphics Object with the specified parameters, based on the original
  53.      * Graphics Object. 
  54.      * This method translates the specified parameters, x and y, to
  55.      * the proper origin coordinates and then clips the Graphics Object to the
  56.      * area.
  57.      * @param x the x coordinate
  58.      * @param y the y coordinate
  59.      * @param width the width of the area
  60.      * @param height the height of the area
  61.      * @see #translate
  62.      */
  63.     public Graphics create(int x, int y, int width, int height) {
  64.     Graphics g = create();
  65.     g.translate(x, y);
  66.     g.clipRect(0, 0, width, height);
  67.     return g;
  68.     }
  69.  
  70.     /**
  71.      * Translates the specified parameters into the origin of the graphics context. All subsequent
  72.      * operations on this graphics context will be relative to this origin.
  73.      * @param x the x coordinate
  74.      * @param y the y coordinate
  75.      */
  76.     public abstract void translate(int x, int y);
  77.  
  78.     /**
  79.      * Gets the current color.
  80.      * @see #setColor
  81.      */
  82.     public abstract Color getColor();
  83.  
  84.     /**
  85.      * Sets the current color to the specified color. All subsequent graphics operations
  86.      * will use this specified color.
  87.      * @param c the color to be set
  88.      * @see Color
  89.      * @see #getColor
  90.      */
  91.     public abstract void setColor(Color c);
  92.  
  93.     /**
  94.      * Sets the paint mode to overwrite the destination with the
  95.      * current color. 
  96.      */
  97.     public abstract void setPaintMode();
  98.  
  99.     /**
  100.      * Sets the paint mode to alternate between the current color
  101.      * and the new specified color.  When drawing operations are
  102.      * performed, pixels which are the current color will be changed
  103.      * to the specified color and vice versa.  Pixels of colors other
  104.      * than those two colors will be changed in an unpredictable, but
  105.      * reversible manner - if you draw the same figure twice then all
  106.      * pixels will be restored to their original values.
  107.      * @param c1 the second color
  108.      */
  109.     public abstract void setXORMode(Color c1);
  110.  
  111.     /**
  112.      * Gets the current font.
  113.      * @see #setFont
  114.      */
  115.     public abstract Font getFont();
  116.  
  117.     /**
  118.      * Sets the font for all subsequent text-drawing operations.
  119.      * @param font the specified font
  120.      * @see Font
  121.      * @see #getFont
  122.      * @see #drawString
  123.      * @see #drawBytes
  124.      * @see #drawChars
  125.     */
  126.     public abstract void setFont(Font font);
  127.  
  128.     /**
  129.      * Gets the current font metrics.
  130.      * @see #getFont
  131.      */
  132.     public FontMetrics getFontMetrics() {
  133.     return getFontMetrics(getFont());
  134.     }
  135.  
  136.     /**
  137.      * Gets the current font metrics for the specified font.
  138.      * @param f the specified font
  139.      * @see #getFont
  140.      * @see #getFontMetrics
  141.      */
  142.     public abstract FontMetrics getFontMetrics(Font f);
  143.  
  144.  
  145.     /** 
  146.      * Returns the bounding rectangle of the current clipping area.
  147.      * @see #clipRect
  148.      */
  149.     public abstract Rectangle getClipRect();
  150.  
  151.     /** 
  152.      * Clips to a rectangle. The resulting clipping area is the
  153.      * intersection of the current clipping area and the specified
  154.      * rectangle. Graphic operations have no effect outside of the
  155.      * clipping area.
  156.      * @param x the x coordinate
  157.      * @param y the y coordinate
  158.      * @param width the width of the rectangle
  159.      * @param height the height of the rectangle
  160.      * @see #getClipRect
  161.      */
  162.     public abstract void clipRect(int x, int y, int width, int height);
  163.  
  164.     /**
  165.      * Copies an area of the screen.
  166.      * @param x the x-coordinate of the source
  167.      * @param y the y-coordinate of the source
  168.      * @param width the width
  169.      * @param height the height
  170.      * @param dx the horizontal distance
  171.      * @param dy the vertical distance
  172.      */
  173.     public abstract void copyArea(int x, int y, int width, int height, int dx, int dy);
  174.  
  175.     /** 
  176.      * Draws a line between the coordinates (x1,y1) and (x2,y2). The line is drawn
  177.      * below and to the left of the logical coordinates.
  178.      * @param x1 the first point's x coordinate
  179.      * @param y1 the first point's y coordinate
  180.      * @param x2 the second point's x coordinate
  181.      * @param y2 the second point's y coordinate
  182.      */
  183.     public abstract void drawLine(int x1, int y1, int x2, int y2);
  184.  
  185.     /** 
  186.      * Fills the specified rectangle with the current color. 
  187.      * @param x the x coordinate
  188.      * @param y the y coordinate
  189.      * @param width the width of the rectangle
  190.      * @param height the height of the rectangle
  191.      * @see #drawRect
  192.      * @see #clearRect
  193.      */
  194.     public abstract void fillRect(int x, int y, int width, int height);
  195.  
  196.     /** 
  197.      * Draws the outline of the specified rectangle using the current color.
  198.      * Use drawRect(x, y, width-1, height-1) to draw the outline inside the specified
  199.      * rectangle.
  200.      * @param x the x coordinate
  201.      * @param y the y coordinate
  202.      * @param width the width of the rectangle
  203.      * @param height the height of the rectangle
  204.      * @see #fillRect
  205.      * @see #clearRect
  206.      */
  207.     public void drawRect(int x, int y, int width, int height) {
  208.     drawLine(x, y, x + width, y);
  209.     drawLine(x + width, y, x + width, y + height);
  210.     drawLine(x, y, x, y + height);
  211.     drawLine(x, y + height, x + width, y + height);
  212.     }
  213.     
  214.     /** 
  215.      * Clears the specified rectangle by filling it with the current background color
  216.      * of the current drawing surface.
  217.      * Which drawing surface it selects depends on how the graphics context
  218.      * was created.
  219.      * @param x the x coordinate
  220.      * @param y the y coordinate
  221.      * @param width the width of the rectangle
  222.      * @param height the height of the rectangle
  223.      * @see #fillRect
  224.      * @see #drawRect
  225.      */
  226.     public abstract void clearRect(int x, int y, int width, int height);
  227.  
  228.     /** 
  229.      * Draws an outlined rounded corner rectangle using the current color.
  230.      * @param x the x coordinate
  231.      * @param y the y coordinate
  232.      * @param width the width of the rectangle
  233.      * @param height the height of the rectangle
  234.      * @param arcWidth the horizontal diameter of the arc at the four corners
  235.      * @param arcHeight the horizontal diameter of the arc at the four corners
  236.      * @see #fillRoundRect
  237.      */
  238.     public abstract void drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
  239.  
  240.     /** 
  241.      * Draws a rounded rectangle filled in with the current color.
  242.      * @param x the x coordinate
  243.      * @param y the y coordinate
  244.      * @param width the width of the rectangle
  245.      * @param height the height of the rectangle
  246.      * @param arcWidth the horizontal diameter of the arc at the four corners
  247.      * @param arcHeight the horizontal diameter of the arc at the four corners
  248.      * @see #drawRoundRect
  249.      */
  250.     public abstract void fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
  251.  
  252.     /**
  253.      * Draws a highlighted 3-D rectangle.
  254.      * @param x the x coordinate
  255.      * @param y the y coordinate
  256.      * @param width the width of the rectangle
  257.      * @param height the height of the rectangle
  258.      * @param raised a boolean that states whether the rectangle is raised or not
  259.      */
  260.     public void draw3DRect(int x, int y, int width, int height, boolean raised) {
  261.     Color c = getColor();
  262.     Color brighter = c.brighter();
  263.     Color darker = c.darker();
  264.  
  265.     setColor(raised ? brighter : darker);
  266.     drawLine(x, y, x, y + height);
  267.     drawLine(x + 1, y, x + width - 1, y);
  268.     setColor(raised ? darker : brighter);
  269.     drawLine(x + 1, y + height, x + width, y + height);
  270.     drawLine(x + width, y, x + width, y + height - 1);
  271.     setColor(c);
  272.     }    
  273.  
  274.     /**
  275.      * Paints a highlighted 3-D rectangle using the current color.
  276.      * @param x the x coordinate
  277.      * @param y the y coordinate
  278.      * @param width the width of the rectangle
  279.      * @param height the height of the rectangle
  280.      * @param raised a boolean that states whether the rectangle is raised or not
  281.      */
  282.     public void fill3DRect(int x, int y, int width, int height, boolean raised) {
  283.     Color c = getColor();
  284.     Color brighter = c.brighter();
  285.     Color darker = c.darker();
  286.  
  287.     if (!raised) {
  288.         setColor(darker);
  289.     }
  290.     fillRect(x+1, y+1, width-2, height-2);
  291.     setColor(raised ? brighter : darker);
  292.     drawLine(x, y, x, y + height - 1);
  293.     drawLine(x + 1, y, x + width - 2, y);
  294.     setColor(raised ? darker : brighter);
  295.     drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
  296.     drawLine(x + width - 1, y, x + width - 1, y + height - 2);
  297.     setColor(c);
  298.     }    
  299.  
  300.     /** 
  301.      * Draws an oval inside the specified rectangle using the current color.
  302.      * @param x the x coordinate
  303.      * @param y the y coordinate
  304.      * @param width the width of the rectangle
  305.      * @param height the height of the rectangle
  306.      * @see #fillOval
  307.      */
  308.     public abstract void drawOval(int x, int y, int width, int height);
  309.  
  310.     /** 
  311.      * Fills an oval inside the specified rectangle using the current color.
  312.      * @param x the x coordinate
  313.      * @param y the y coordinate
  314.      * @param width the width of the rectangle
  315.      * @param height the height of the rectangle
  316.      * @see #drawOval
  317.      */
  318.     public abstract void fillOval(int x, int y, int width, int height);
  319.  
  320.     /**
  321.      * Draws an arc bounded by the specified rectangle from startAngle to
  322.      * endAngle. 0 degrees is at the 3-o'clock position.Positive arc
  323.      * angles indicate counter-clockwise rotations, negative arc angles are
  324.      * drawn clockwise. 
  325.      * @param x the x coordinate
  326.      * @param y the y coordinate
  327.      * @param width the width of the rectangle
  328.      * @param height the height of the rectangle
  329.      * @param startAngle the beginning angle
  330.      * @param arcAngle the angle of the arc (relative to startAngle).
  331.      * @see #fillArc
  332.      */
  333.     public abstract void drawArc(int x, int y, int width, int height, int startAngle, int arcAngle);
  334.  
  335.     /** 
  336.      * Fills an arc using the current color. This generates a pie shape.
  337.      *
  338.      * @param x the x coordinate
  339.      * @param y the y coordinate
  340.      * @param width the width of the arc
  341.      * @param height the height of the arc
  342.      * @param startAngle the beginning angle
  343.      * @param arcAngle the angle of the arc (relative to startAngle).
  344.      * @see #drawArc
  345.      */
  346.     public abstract void fillArc(int x, int y, int width, int height, int startAngle, int arcAngle);
  347.  
  348.     /** 
  349.      * Draws a polygon defined by an array of x points and y points.
  350.      * @param xPoints an array of x points
  351.      * @param yPoints an array of y points
  352.      * @param nPoints the total number of points
  353.      * @see #fillPolygon
  354.      */
  355.     public abstract void drawPolygon(int xPoints[], int yPoints[], int nPoints);
  356.  
  357.     /** 
  358.      * Draws a polygon defined by the specified point.
  359.      * @param p the specified polygon
  360.      * @see #fillPolygon
  361.      */
  362.     public void drawPolygon(Polygon p) {
  363.     drawPolygon(p.xpoints, p.ypoints, p.npoints);
  364.     }
  365.  
  366.     /** 
  367.      * Fills a polygon with the current color using an
  368.      * even-odd fill rule (otherwise known as an alternating rule).
  369.      * @param xPoints an array of x points
  370.      * @param yPoints an array of y points
  371.      * @param nPoints the total number of points
  372.      * @see #drawPolygon
  373.      */
  374.     public abstract void fillPolygon(int xPoints[], int yPoints[], int nPoints);
  375.  
  376.     /** 
  377.      * Fills the specified polygon with the current color using an
  378.      * even-odd fill rule (otherwise known as an alternating rule).
  379.      * @param p the polygon
  380.      * @see #drawPolygon
  381.      */
  382.     public void fillPolygon(Polygon p) {
  383.     fillPolygon(p.xpoints, p.ypoints, p.npoints);
  384.     }
  385.  
  386.     /** 
  387.      * Draws the specified String using the current font and color.
  388.      * The x,y position is the starting point of the baseline of the String.
  389.      * @param str the String to be drawn
  390.      * @param x the x coordinate
  391.      * @param y the y coordinate
  392.      * @see #drawChars
  393.      * @see #drawBytes
  394.      */
  395.     public abstract void drawString(String str, int x, int y);
  396.  
  397.     /** 
  398.      * Draws the specified characters using the current font and color.
  399.      * @param data the array of characters to be drawn
  400.      * @param offset the start offset in the data
  401.      * @param length the number of characters to be drawn
  402.      * @param x the x coordinate
  403.      * @param y the y coordinate
  404.      * @see #drawString
  405.      * @see #drawBytes
  406.      */
  407.     public void drawChars(char data[], int offset, int length, int x, int y) {
  408.     drawString(new String(data, offset, length), x, y);
  409.     }
  410.  
  411.     /** 
  412.      * Draws the specified bytes using the current font and color.
  413.      * @param data the data to be drawn
  414.      * @param offset the start offset in the data
  415.      * @param length the number of bytes that are drawn
  416.      * @param x the x coordinate
  417.      * @param y the y coordinate
  418.      * @see #drawString
  419.      * @see #drawChars
  420.      */
  421.     public void drawBytes(byte data[], int offset, int length, int x, int y) {
  422.     drawString(new String(data, 0, offset, length), x, y);
  423.     }
  424.  
  425.     /** 
  426.      * Draws the specified image at the specified coordinate (x, y). If the image is 
  427.      * incomplete the image observer will be notified later.
  428.      * @param img the specified image to be drawn
  429.      * @param x the x coordinate
  430.      * @param y the y coordinate
  431.      * @param observer notifies if the image is complete or not
  432.      * @see Image
  433.      * @see ImageObserver
  434.      */
  435.     public abstract boolean drawImage(Image img, int x, int y, 
  436.                       ImageObserver observer);
  437.  
  438.     /**
  439.      * Draws the specified image inside the specified rectangle. The image is
  440.      * scaled if necessary. If the image is incomplete the image observer will be
  441.      * notified later.
  442.      * @param img the specified image to be drawn
  443.      * @param x the x coordinate
  444.      * @param y the y coordinate
  445.      * @param width the width of the rectangle
  446.      * @param height the height of the rectangle
  447.      * @param observer notifies if the image is complete or not
  448.      * @see Image
  449.      * @see ImageObserver
  450.      */
  451.     public abstract boolean drawImage(Image img, int x, int y,
  452.                       int width, int height, 
  453.                       ImageObserver observer);
  454.     
  455.     /** 
  456.      * Draws the specified image at the specified coordinate (x, y),
  457.      * with the given solid background Color.  If the image is 
  458.      * incomplete the image observer will be notified later.
  459.      * @param img the specified image to be drawn
  460.      * @param x the x coordinate
  461.      * @param y the y coordinate
  462.      * @param observer notifies if the image is complete or not
  463.      * @see Image
  464.      * @see ImageObserver
  465.      */
  466.     public abstract boolean drawImage(Image img, int x, int y, 
  467.                       Color bgcolor,
  468.                       ImageObserver observer);
  469.  
  470.     /**
  471.      * Draws the specified image inside the specified rectangle,
  472.      * with the given solid background Color. The image is
  473.      * scaled if necessary. If the image is incomplete the image
  474.      * observer will be notified later.
  475.      * @param img the specified image to be drawn
  476.      * @param x the x coordinate
  477.      * @param y the y coordinate
  478.      * @param width the width of the rectangle
  479.      * @param height the height of the rectangle
  480.      * @param observer notifies if the image is complete or not
  481.      * @see Image
  482.      * @see ImageObserver
  483.      */
  484.     public abstract boolean drawImage(Image img, int x, int y,
  485.                       int width, int height, 
  486.                       Color bgcolor,
  487.                       ImageObserver observer);
  488.     
  489.     /**
  490.      * Disposes of this graphics context.  The Graphics context cannot be used after 
  491.      * being disposed of.
  492.      * @see #finalize
  493.      */
  494.     public abstract void dispose();
  495.  
  496.     /**
  497.      * Disposes of this graphics context once it is no longer referenced.
  498.      * @see #dispose
  499.      */
  500.     public void finalize() {
  501.     dispose();
  502.     }
  503.  
  504.     /**
  505.      * Returns a String object representing this Graphic's value.
  506.      */
  507.     public String toString() {    
  508.     return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
  509.     }
  510.  
  511. }
  512.